@claudelaw/taichu 0.6.0

package/.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+.git
+.taichu
+*.md
+!README.md
+.vscode
+.idea
+*.log
+coverage
+.nyc_output
+dist
+.DS_Store
+Thumbs.db

package/Dockerfile

@@ -0,0 +1,51 @@
+# Taichu CMS — Docker 镜像
+#
+# 构建: docker build -t taichu .
+# 运行: docker run -p 3120:3120 -v taichu-data:/app/.taichu taichu
+#
+# 默认使用 SQLite 存储，数据持久化到 .taichu/ 目录。
+
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY packages/core/package.json packages/core/
+COPY packages/server/package.json packages/server/
+COPY packages/mcp/package.json packages/mcp/
+COPY packages/admin/package.json packages/admin/
+
+# Install dependencies
+RUN npm install --omit=dev 2>/dev/null || npm install
+
+# Copy source
+COPY . .
+
+# Build admin SPA
+RUN cd packages/admin && npx vite build 2>/dev/null || echo "Admin build skipped (pre-built)"
+
+FROM node:22-alpine
+
+WORKDIR /app
+
+# Copy only what's needed for runtime
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/packages/core ./packages/core
+COPY --from=builder /app/packages/server ./packages/server
+COPY --from=builder /app/packages/mcp ./packages/mcp
+
+ENV NODE_ENV=production
+ENV TAICHU_STORAGE=sqlite
+ENV TAICHU_PORT=3120
+ENV TAICHU_HOST=0.0.0.0
+
+EXPOSE 3120
+
+VOLUME ["/app/.taichu"]
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3120/api/health',r=>{let d='';r.on('data',c=>d+=c);r.on('end',()=>process.exit(d.includes('ok')?0:1))})"
+
+CMD ["node", "packages/server/src/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liu Huai'an (刘淮安) and Taichu contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Taichu" width="360" />
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg" alt="License: MIT" /></a>
+  <a href="#"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node.js >= 18" /></a>
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome" /></a>
+  <a href="#"><img src="https://img.shields.io/badge/stage-alpha-orange.svg" alt="Alpha Stage" /></a>
+</p>
+
+---
+
+## What is Taichu?
+
+Taichu is a **content management system built for the AI agent era**. While WordPress and Typecho were architected for human authors editing HTML in a browser, Taichu is architected for a world where AI agents are first-class content producers and consumers.
+
+### The Problem
+
+- **WordPress / Typecho** store content as HTML strings in a database, designed for one human editing in a WYSIWYG editor and another human reading on a themed page
+- **Headless CMS** (Strapi, Directus) separate content from presentation, but are still designed for human authors
+- **AI agents** need structured, semantic content with discoverable APIs, fine-grained permissions, and content pipelines
+
+### Our Answer
+
+Taichu treats **AI agents as first-class citizens** alongside human authors:
+
+| | Traditional CMS | Headless CMS | **Taichu** |
+|---|---|---|---|
+| Authors | Humans only | Humans only | **Humans + AI Agents** |
+| Content format | HTML strings | Structured JSON | **Semantic JSON-LD** |
+| API | Afterthought (REST API plugin) | Primary (REST / GraphQL) | **Native (REST + GraphQL + MCP)** |
+| Search | SQL LIKE | Full-text index | **Vector + Semantic** |
+| Plugin model | Human-oriented (widgets, SEO) | Webhooks | **Agent Capability Extensions** |
+| Permissions | Role-based (admin/editor/author) | Role-based | **Identity-based (Human + Agent + Scope)** |
+| Deployment | LAMP stack | Docker / Cloud | **Single binary or Docker** |
+
+---
+
+## Philosophy
+
+### Content as Data, Not HTML
+
+Taichu stores structured data — not HTML blobs. An article is a document with typed fields (`title: string`, `body: json`, `tags: array`), not a `wp_post` row with a `post_content` column full of HTML.
+
+This means:
+- AI agents can read and write content without parsing HTML
+- Rendering is separated from storage — same content can be a web page, RSS feed, or agent response
+- Relationships are native — fields can be typed as `relation` to other content types
+- Search is semantic — embedding vectors live alongside structured fields
+
+### Agents Are First-Class Citizens
+
+Every API endpoint, permission, and workflow is designed for both human and agent consumers:
+
+```bash
+# Human access (JWT)
+curl -H "Authorization: Bearer $JWT_TOKEN" \
+  https://taichu.example.com/api/content/article
+
+# Agent access (API Key)
+curl -H "X-Taichu-Agent-Key: $AGENT_KEY" \
+  https://taichu.example.com/api/content/article
+```
+
+Agent-specific features:
+- **Rate limiting per agent** — prevent runaway agents from overwhelming the system
+- **Content pipelines** — agents can register as processors in content workflows
+- **Audit trails** — every agent action is logged and attributable
+- **MCP protocol** — agents discover Taichu's capabilities automatically via Model Context Protocol (Phase 2)
+
+### Zero Dependencies (Core)
+
+The core runtime depends only on Node.js built-in modules. No npm install dance, no dependency hell. This is a deliberate choice:
+
+- **Auditability** — every line of code can be reviewed
+- **Longevity** — no risk of left-pad incidents
+- **Performance** — no framework overhead
+- **Simplicity** — `git clone && npm start` just works
+
+*Optional dependencies (SQLite driver, vector store) will be clearly documented and isolated.*
+
+### Extensible by Design
+
+Like WordPress's plugin system, but for agents:
+
+```js
+// Register a content type
+taichu.registerContentType(createContentType('product', {
+  label: 'Product',
+  fields: {
+    name: { type: 'string', required: true },
+    price: { type: 'number' },
+    description: { type: 'json' }
+  }
+}));
+
+// Hook into the content pipeline
+taichu.hooks.on('afterCreate', async (doc, ctx) => {
+  if (doc.type === 'article') {
+    await autoGenerateExcerpt(doc);
+    await indexForSearch(doc);
+  }
+});
+
+// Agent capability extension
+taichu.hooks.on('agent:onRequest', async (payload, ctx) => {
+  if (ctx.agent.scope === 'seo-optimizer') {
+    payload.enhancements = ['keywords', 'readability'];
+  }
+});
+```
+
+---
+
+## Quick Start
+
+```bash
+# Clone
+git clone https://github.com/Caludelaw/Taichu.git
+cd taichu
+
+# Run (yes, that's it — zero npm install needed for core)
+npm start
+
+# Taichu is now running at http://localhost:3120
+# Health check: http://localhost:3120/api/health
+```
+
+### Create Your First Content
+
+```bash
+# Create a document
+curl -X POST http://localhost:3120/api/content/article \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "title": "Hello Taichu",
+      "body": {"text": "Welcome to the agent-native CMS."},
+      "status": "published"
+    }
+  }'
+
+# List all articles
+curl http://localhost:3120/api/content/article
+
+# Get a single article
+curl http://localhost:3120/api/content/article/<id>
+```
+
+---
+
+## Project Structure
+
+```
+taichu/
+├── packages/
+│   ├── core/           # Content model, storage abstraction, hook system
+│   │   └── src/
+│   │       ├── content-type.js   # Schema definition & validation
+│   │       ├── store.js          # Storage interface + MemoryStore
+│   │       ├── hooks.js          # Lifecycle hook system
+│   │       └── errors.js         # Structured error types
+│   ├── server/         # HTTP server (zero-dependency)
+│   │   └── src/
+│   │       ├── index.js          # Server entry point
+│   │       ├── router.js         # URL routing
+│   │       ├── context.js        # Request context
+│   │       └── routes/
+│   │           └── api.js        # REST API implementation
+│   ├── mcp/            # MCP Server (Phase 2)
+│   └── admin/          # Vue 3 Admin SPA (Phase 2)
+├── docs/
+│   ├── architecture/   # Architecture Decision Records (ADRs)
+│   ├── api/            # API documentation
+│   └── guides/         # User & developer guides
+├── .github/
+│   └── workflows/      # CI/CD pipelines
+├── LICENSE             # MIT
+├── CONTRIBUTING.md     # Contribution guide
+└── CODE_OF_CONDUCT.md  # Community standards
+```
+
+---
+
+## Development Roadmap
+
+| Phase | Focus | Status |
+|-------|-------|--------|
+| **Phase 1** | Core CMS: content model, REST API, memory store | 🚧 Alpha |
+| **Phase 2** | AI-Native: vector search, MCP, agent permissions, GraphQL | 📋 Planned |
+| **Phase 3** | Ecosystem: extension marketplace, multi-agent collaboration, federation | 📋 Planned |
+
+See [ROADMAP.md](docs/ROADMAP.md) for details.
+
+---
+
+## Contributing
+
+Taichu is in active early development. We welcome contributions from developers who share our vision of agent-native content infrastructure.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, and check [GitHub Issues](https://github.com/Caludelaw/Taichu/issues) for tasks tagged `good first issue`.
+
+---
+
+## License
+
+MIT © 2026 Liu Huai'an and Taichu contributors. See [LICENSE](LICENSE).

package/docker-compose.yml

@@ -0,0 +1,42 @@
+# Taichu CMS — Docker Compose 一键部署
+#
+# 使用方法：
+#   开发环境：docker compose up
+#   生产环境：docker compose up -d
+#
+# 环境变量配置：
+#   TAICHU_PORT       — 服务端口，默认 3120
+#   TAICHU_SECRET     — JWT 签名密钥（生产环境必改）
+#   TAICHU_ADMIN_USER — 初始管理员用户名
+#   TAICHU_ADMIN_PASS — 初始管理员密码
+
+services:
+  taichu:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: taichu-cms
+    ports:
+      - "${TAICHU_PORT:-3120}:3120"
+    environment:
+      - NODE_ENV=production
+      - TAICHU_STORAGE=sqlite
+      - TAICHU_PORT=3120
+      - TAICHU_HOST=0.0.0.0
+      - TAICHU_PUBLIC_READ=1
+      - TAICHU_SECRET=${TAICHU_SECRET:-change-me-in-production}
+      - TAICHU_ADMIN_USER=${TAICHU_ADMIN_USER:-admin}
+      - TAICHU_ADMIN_PASS=${TAICHU_ADMIN_PASS:-admin123}
+    volumes:
+      - taichu-data:/app/.taichu
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3120/api/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    restart: unless-stopped
+
+volumes:
+  taichu-data:
+    driver: local

package/docs/ROADMAP.md

@@ -0,0 +1,101 @@
+# Taichu Development Roadmap
+
+## Phase 1: Core CMS ✅ COMPLETE
+
+**Goal**: A working headless CMS with structured content, REST API, and hook-based extension system.
+
+| Feature | Status | Package |
+|---------|--------|---------|
+| Content Type Schema Definition | ✅ Done | `@taichu/core` |
+| Typed Field Validation | ✅ Done | `@taichu/core` |
+| Memory Store (dev/testing) | ✅ Done | `@taichu/core` |
+| Hook System (lifecycle hooks) | ✅ Done | `@taichu/core` |
+| Structured Error Types | ✅ Done | `@taichu/core` |
+| Zero-Dependency HTTP Server | ✅ Done | `@taichu/server` |
+| REST API (CRUD + list) | ✅ Done | `@taichu/server` |
+| CORS Middleware | ✅ Done | `@taichu/server` |
+| JSON Body Parser | ✅ Done | `@taichu/server` |
+| Architecture Decision Records | ✅ Done | `docs/` |
+| SQLite Store (sql.js WASM) | ✅ Done | `@taichu/core` |
+| Authentication (JWT + API Key) | ✅ Done | `@taichu/core` |
+| Vue 3 Admin SPA | ✅ Done | `@taichu/admin` |
+| Static File Serving | ✅ Done | `@taichu/server` |
+
+## Phase 2: AI-Native ✅ COMPLETE
+
+**Goal**: AI agents become first-class content consumers and producers.
+
+| Feature | Status |
+|---------|--------|
+| Agent API Key Authentication | ✅ Done |
+| JWT Authentication (Human) | ✅ Done |
+| MCP Server (stdio transport, 29 tools) | ✅ Done |
+| TF-IDF Vector Search | ✅ Done |
+| Content Auto-Indexing (hook-based) | ✅ Done |
+| GraphQL API | ✅ Done |
+| Content Pipeline Engine (3 built-in templates) | ✅ Done |
+| Agent Permission Scopes | ✅ Done |
+| Content Localization (ZHHK/EN/JP) | ✅ Done |
+| SSO Framework (OIDC + LDAP) | ✅ Done |
+| Webhook System | ✅ Done |
+| Audit Logging (append-only) | ✅ Done |
+
+## Phase 3: Ecosystem ✅ COMPLETE
+
+**Goal**: Developer ecosystem with extensions, themes, and real-time collaboration.
+
+| Feature | Status |
+|---------|--------|
+| WebSocket Real-Time Updates | ✅ Done |
+| Multi-Agent Collaboration Engine | ✅ Done |
+| Plugin Manager (backend) | ✅ Done |
+| Theme System (custom upload, __TAICHU__ injection) | ✅ Done |
+| Admin SPA (18 pages, 3 locales) | ✅ Done |
+| Content Revisions (field-level diff, max 100) | ✅ Done |
+| Rate Limiting (token bucket, 3 dimensions) | ✅ Done |
+| Notification Channels (Feishu/DingTalk/WeCom) | ✅ Done |
+| CLI (init/dev/migrate) | ✅ Done |
+| Docker Support | ✅ Done |
+| CI/CD (GitHub Actions + Gitee mirror) | ✅ Done |
+| ESLint Code Quality | ✅ Done |
+
+## v0.4.0 → v0.5.0 (Current)
+
+| Feature | Priority | Status |
+|---------|----------|--------|
+| Server Integration Tests | P0 | ✅ Done |
+| ROADMAP & Docs Update | P0 | ✅ Done |
+| Brand Icon Redesign (Tai Chi ball) | P0 | ✅ Done |
+| Scheduled Publishing | P1 | ✅ Done |
+| Version Diff API | P1 | ✅ Done |
+| Docker Compose One-Click Deploy | P1 | ✅ Done |
+| Media Library Enhancement (compress/WebP/thumbs) | P1 | ✅ Done |
+| Email Notification Channel | P2 | ✅ Done |
+| Content Relationship Graph | P2 | ✅ Done |
+| Multi-Tenant Support | P2 | ✅ Done |
+| Plugin Marketplace (frontend + CLI install) | P2 | ✅ Done |
+| ActivityPub Federation | P2 | ✅ Done |
+
+## v0.5.0 → v0.6.0 (Current)
+
+| Feature | Priority | Status |
+|---------|----------|--------|
+| Dashboard Charts (content stats, trend graphs) | P1 | ✅ Done |
+| Theme Frontend Pagination (blog list pages) | P1 | ✅ Done |
+| Content Relationships Graph UI (admin visualization) | P1 | ✅ Done |
+| Media Selector in Rich Editor | P1 | ✅ Done |
+| Batch Operations (bulk delete/publish) | P2 | ✅ Done |
+| Second Official Theme (minimal/portfolio) | P2 | ✅ Done |
+| SSO OIDC Callback Handler | P2 | Todo |
+| E2E Tests (Playwright, core flows) | P2 | Todo |
+| API Reference Documentation | P2 | Todo |
+| Custom Field Types (date, boolean, reference) | P3 | Todo |
+| Content Export (JSON, Markdown, CSV) | P3 | Todo |
+| Webhook Retry with Exponential Backoff | P3 | Todo |
+
+## Long-Term Vision
+
+- **Taichu as content backbone for AI agent ecosystems** — every agent in a workflow uses Taichu as its shared content infrastructure
+- **Federated content networks** — Taichu instances discover and share content via ActivityPub
+- **Agent marketplace** — developers publish agent capabilities as installable extensions
+- **Zero-config HA** — SQLite + Litestream for production-grade durability with single-binary simplicity

package/docs/api/README.md

@@ -0,0 +1,102 @@
+# Taichu API Documentation
+
+## Overview
+
+Taichu is API-first. Everything you can do in the admin UI, you can do via the API.
+
+- **Base URL**: `http://localhost:3120/api`
+- **Content-Type**: `application/json`
+- **Authentication**: JWT (humans) or API Key (agents) — coming in Phase 2
+
+## Endpoints
+
+### Health Check
+
+```
+GET /api/health
+```
+
+Response:
+```json
+{
+  "status": "ok",
+  "name": "taichu",
+  "version": "0.1.0",
+  "uptime": 123.456
+}
+```
+
+### Content Types
+
+```
+GET /api/content-types
+```
+
+Returns all registered content types.
+
+```
+GET /api/content-types/:name
+```
+
+Returns the JSON Schema for a specific content type.
+
+### Content CRUD
+
+```
+GET    /api/content/:type          # List documents of type
+POST   /api/content/:type          # Create a document
+GET    /api/content/:type/:id      # Get a single document
+PUT    /api/content/:type/:id      # Update a document
+DELETE /api/content/:type/:id      # Delete a document
+```
+
+#### Query Parameters (for `GET /api/content/:type`)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `status` | string | Filter by status (`draft`, `published`, `archived`) |
+| `search` | string | Full-text search across document data |
+| `limit` | number | Max results (default: 50) |
+| `offset` | number | Pagination offset |
+| `orderBy` | string | Sort field (default: `updatedAt`) |
+| `order` | string | Sort direction (`asc` or `desc`, default: `desc`) |
+
+#### Examples
+
+```bash
+# List all published articles
+curl http://localhost:3120/api/content/article?status=published
+
+# Create a new article
+curl -X POST http://localhost:3120/api/content/article \
+  -H "Content-Type: application/json" \
+  -d '{"data":{"title":"Hello World","body":{"text":"First post!"}}}'
+
+# Update an article
+curl -X PUT http://localhost:3120/api/content/article/doc-123 \
+  -H "Content-Type: application/json" \
+  -d '{"data":{"title":"Updated Title"}}'
+
+# Delete an article
+curl -X DELETE http://localhost:3120/api/content/article/doc-123
+```
+
+## Error Responses
+
+All errors follow this format:
+
+```json
+{
+  "error": "ERROR_CODE",
+  "message": "Human-readable description",
+  "status": 400
+}
+```
+
+Error codes:
+- `VALIDATION_ERROR` (400) — request body doesn't match content type schema
+- `NOT_FOUND` (404) — resource doesn't exist
+- `UNAUTHORIZED` (401) — missing or invalid credentials (Phase 2)
+- `FORBIDDEN` (403) — insufficient permissions (Phase 2)
+- `CONFLICT` (409) — resource conflict (e.g., duplicate slug)
+- `INTERNAL_ERROR` (500) — unexpected server error

package/docs/architecture/001-zero-dependency-core.md

@@ -0,0 +1,61 @@
+# ADR 001: Zero-Dependency Core Runtime
+
+- **Status:** Accepted
+- **Date:** 2026-06-06
+- **Author:** Liu Huai'an
+
+## Context
+
+We need to choose the dependency strategy for Taichu's core runtime (`@taichu/core` and `@taichu/server`). The options range from full-framework (Express/Fastify + ORM + etc.) to zero-dependency (Node.js built-ins only).
+
+## Decision Drivers
+
+1. **Auditability** — open-source contributors must be able to understand every line of code
+2. **Longevity** — the project should remain viable for 10+ years without dependency churn
+3. **Performance** — minimal overhead for core operations
+4. **Install simplicity** — `git clone && npm start` should work immediately
+5. **Extensibility** — power users can swap in heavier dependencies when needed
+
+## Options Considered
+
+### Option A: Full Framework (Express + Prisma + etc.)
+
+- **Pros**: Rapid development, familiar patterns, large ecosystem
+- **Cons**: Heavy dependency tree, breaking changes risk, "magic" behavior
+
+### Option B: Minimal Dependencies (Fastify or Hono)
+
+- **Pros**: Lighter than Express, modern APIs, maintained
+- **Cons**: Still external dependencies, version drift risk
+
+### Option C: Zero Dependencies (Node.js built-ins only)
+
+- **Pros**: Maximum auditability, zero supply-chain risk, instant startup, eternal viability
+- **Cons**: More code to write, less "batteries included"
+
+## Decision
+
+**We choose Option C: Zero Dependencies for the core runtime.**
+
+The core packages (`@taichu/core`, `@taichu/server`) use only Node.js built-in modules. Optional dependencies (SQLite driver, vector store) are isolated in separate packages.
+
+## Consequences
+
+### Positive
+
+- `git clone && npm start` works with zero `npm install` for core
+- Every line of code is auditable by any Node.js developer
+- No left-pad incidents, no dependency confusion attacks
+- Cold start time is measured in milliseconds, not seconds
+
+### Negative
+
+- We write our own HTTP router, body parser, and middleware stack
+- Fewer "batteries included" — developers migrating from Express need to learn our API
+- Some features (file upload parsing, WebSocket) require more effort
+
+### Mitigations
+
+- Clear JSDoc documentation for all public APIs
+- The API design is intentionally similar to familiar patterns (middleware stack, context object)
+- Complex features that truly need external deps are in separate packages (e.g., `@taichu/driver-sqlite`)

package/docs/architecture/002-structured-content-model.md

@@ -0,0 +1,70 @@
+# ADR 002: Structured Content Model with JSON-LD
+
+- **Status:** Accepted
+- **Date:** 2026-06-06
+- **Author:** Liu Huai'an
+
+## Context
+
+Traditional CMS (WordPress, Typecho) store content as HTML strings in a `post_content` column. Headless CMS (Strapi, Directus) store structured JSON but without semantic markup. For an agent-native CMS, we need content to be both structured and semantically meaningful.
+
+## Decision Drivers
+
+1. **Machine readability** — AI agents must be able to parse and understand content without HTML scraping
+2. **Semantic interoperability** — content should map to standard vocabularies (schema.org, JSON-LD)
+3. **Multi-format output** — same content should render as HTML, RSS, JSON-LD, or agent response
+4. **Validation** — content type schemas should be enforceable at the API level
+
+## Options Considered
+
+### Option A: HTML String Storage (WordPress model)
+
+Rejected: AI agents must parse HTML to extract meaning. Loses structured data. Not forward-compatible.
+
+### Option B: Generic JSON (Strapi model)
+
+Rejected: Structured but not semantic. No standard way to map fields to schema.org types. Agents must guess what each field means.
+
+### Option C: JSON-LD with Content Type Schemas (our approach)
+
+Accepted: Each content type registers a schema (typed fields + validation rules + optional schema.org mapping). Documents are stored as structured JSON. The API can output JSON-LD for search engines and structured JSON for agents.
+
+## Decision
+
+**Taichu uses typed content type schemas with optional JSON-LD semantic markup.**
+
+Each content type:
+1. Defines typed fields (`string`, `number`, `json`, `array`, `enum`, `datetime`, `media`, `relation`)
+2. Has validation rules (required, maxLength, pattern, enum values)
+3. Can map to a schema.org type (e.g., `schemaOrg: 'Article'`)
+4. Fields can have semantic property mappings (e.g., `semantic: 'headline'`)
+
+## Content Type Example
+
+```js
+const Article = createContentType('article', {
+  label: 'Article',
+  schemaOrg: 'Article',
+  fields: {
+    title:    { type: 'string',  required: true,  semantic: 'headline' },
+    body:     { type: 'json',    required: true,  semantic: 'articleBody' },
+    excerpt:  { type: 'string',  maxLength: 500,  semantic: 'description' },
+    author:   { type: 'relation', target: 'author', semantic: 'author' },
+    tags:     { type: 'array',   items: { type: 'string' }, semantic: 'keywords' },
+    publishedAt: { type: 'datetime', semantic: 'datePublished' }
+  }
+});
+```
+
+## Consequences
+
+### Positive
+- Content is machine-readable by default
+- Schema validation at the API layer catches errors early
+- JSON-LD output is SEO-friendly and search-engine compatible
+- Agents can introspect content types to understand available fields
+
+### Negative
+- More upfront design work to define content types
+- Migration from HTML-based CMS requires content extraction
+- Not all content naturally fits a typed schema (handled by `json` type for free-form fields)